Skip Headers

Oracle Procedural Gateway® for APPC User's Guide 10g Release 2 (10.2) for Microsoft Windows (32-Bit) Part Number B16212-01 |
Home | Book List | Contents | Index | Master Index | Feedback

Previous | Next
| View PDF

# C The UTL_PG and UTL_RAW Interface

The Oracle Procedural Gateway for APPC requires the use of the RAW datatype to transfer data to and from PL/SQL without any alteration by Oracle Net. This is necessary because only the PL/SQL applications have information about the format of the data being sent to and received from the remote transaction programs. Oracle Net only has information about the systems where the PL/SQL application and the gateway server are running. If Oracle Net is allowed to perform translation on the data flowing between PL/SQL and the gateway, the data can end up in the wrong format.

This appendix contains the following sections:

- "UTL_RAW Functions"

- "UTL_PG Functions"

- "NUMBER_TO_RAW and RAW_TO_NUMBER Argument Values"

## C.1 UTL_RAW Functions

The UTL_RAW package is an extension to PL/SQL that provides a full complement of RAW data manipulation functions. Using these functions, data sent to remote transaction programs can be converted into the correct format by the PL/SQL application, and data received from remote transaction programs can be converted back into Oracle formats.

All of the functions listed in this section are called in the standard PL/SQL manner, which is `package_name.function_name(arguments)`. In the case of the UTL_RAW routines, this is `UTL_RAW.function_name(arguments)`.

For each function listed in the following sections, the function name, arguments and their datatypes, and the return value datatype are provided. Unless otherwise specified, the parameters are IN, not OUT, parameters.

### C.1.1 BIT_AND

BIT_AND performs a bitwise logical AND operation of the values in `r1` and `r2` and returns the resulting value.

If `r1` and `r2` have different lengths, then the AND operation is terminated after the last byte of the shorter of the two RAW values. The unprocessed portion of the longer RAW value is appended to the partial result to produce the final result returned. The result length equals the longer of the two input RAW values.

Syntax

    function BIT_AND (r1 IN RAW, r2 IN RAW) RETURN RAW;

Where Table C-1 describes the parameters in this function:

Table C-1 BIT_AND Function Parameters

Parameter | Description
--- | ---
`r1` | is a RAW value to be combined with `r2`.
`r2` | is a RAW value to be combined with `r1`.

Defaults

None.

Return Value

A RAW value which is the bitwise logical AND of `r1` and `r2`. Or a null value if either `r1` or `r2` is null.

Error and Warning Messages

If you receive an ORA-xxxx error or warning message, refer to the Oracle Database Error Messages guide for an explanation and information about how to handle it.

### C.1.2 BIT_COMPLEMENT

BIT_COMPLEMENT performs a bitwise logical COMPLEMENT operation of the value `r` and returns the resulting RAW value. The length of the result equals the length of the input RAW value `r`.

Syntax

    function BIT_COMPLEMENT (r IN RAW) RETURN RAW;

where:

"r" is the RAW value on which to perform the COMPLEMENT operation.

Defaults

None

Return Value

A RAW value which is the bitwise logical COMPLEMENT of `r`. Or a null value if the input value `r` is null.

Error and Warning Messages

If you receive an ORA-xxxx error or warning message, refer to the Oracle Database Error Messages guide for an explanation and information about how to handle it.

### C.1.3 BIT_OR

BIT_OR performs a bitwise logical OR operation of the values in `r1` and `r2` and returns the resulting value.

If `r1` and `r2` have different lengths, then the OR operation is terminated after the last byte of the shorter of the two RAW values. The unprocessed portion of the longer RAW value is appended to the partial result to produce the final result returned. The resulting length equals the longer of the two input values, `r1` and `r2`.

Syntax

    function BIT_OR (r1 IN RAW, r2 IN RAW) RETURN RAW;

Where Table C-2 describes the parameters in the function:

Table C-2 BIT_OR Function Parameters

Parameter | Description
--- | ---
`r1` | is a RAW value to OR with `r2`.
`r2` | is a RAW value to OR with `r1`.

Defaults

None

Return Value

A RAW value which is the bitwise logical OR of `r1` and `r2`. Or a null value if both `r1` and `r2` is null.

Error and Warning Messages

If you receive an ORA-xxxx error or warning message, refer to the Oracle Database Error Messages guide for an explanation and information about how to handle it.

### C.1.4 BIT_XOR

BIT_XOR performs a bitwise logical EXCLUSIVE OR operation of the values in `r1` and `r2` and returns the resulting value.

If `r1` and `r2` have different lengths, then the EXCLUSIVE OR operation is terminated after the last byte of the shorter of the two RAW values. The unprocessed portion of the longer RAW value is appended to the partial result to produce the final result returned. The result length equals the longer of the two input RAW values.

Syntax

    function BIT_XOR (r1 IN RAW, r2 IN RAW) RETURN RAW

Where Table C-3 describes the parameters in this function:

Table C-3 BIT_XOR Function Parameters

Parameter | Description
--- | ---
`r1` | is the RAW value to XOR with `r2`.
`r2` | is the RAW value to XOR with `r1`.

Defaults

None

Return Value

A RAW value which is the bitwise logical XOR of `r1` and `r2`. Or a null value if `r1` and `r2` have identical values.

Error and Warning Messages

If you receive an ORA-xxxx error or warning message, refer to the Oracle Database Error Messages guide for an explanation and information about how to handle it.

### C.1.5 CAST_TO_RAW

CAST_TO_RAW converts a VARCHAR2 `c` into a RAW with the same number of bytes.

The input is treated as if it is composed of single 8-bit bytes, not characters. Multibyte character boundaries are ignored. The data is not modified in any way, it is just changed to a RAW datatype.

Syntax

    function CAST_TO_RAW (c IN VARCHAR2) RETURN RAW;

where: "`c`" is a VARCHAR2 value to be changed to a RAW value.

Defaults

None

Return Value

A RAW value having the same data and byte length as the input VARCHAR2 value. Or a null value if `c` is null.

Error and Warning Messages

If you receive an ORA-xxxx error or warning message, refer to the Oracle Database Error Messages guide for an explanation and information about how to handle it.

### C.1.6 CAST_TO_VARCHAR2

CAST_TO_VARCHAR2 converts a RAW `r` into a VARCHAR2 with the same number of data bytes.

The result is treated as if it is composed of single 8-bit bytes, not characters. Multibyte character boundaries are ignored. The data is not modified in any way, it is just changed to a VARCHAR2 datatype.

Syntax

    function CAST_TO_VARCHAR2 (r IN RAW) RETURN VARCHAR2;

where:

"`r`" is a RAW value to be changed to a VARCHAR value.

Defaults

None

Return Value

A VARCHAR2 value having the same data as the RAW input value. Or a null value if `r` is null.

Error and Warning Messages

If you receive an ORA-xxxx error or warning message, refer to the Oracle Database Error Messages guide for an explanation and information about how to handle it.

### C.1.7 COMPARE

COMPARE compares RAW `r1` with RAW `r2`.

If they are identical, COMPARE returns zero. Otherwise, COMPARE returns the position of the first byte that does not match. If the input values are of different length, the shorter RAW value is padded on the right with the byte specified by `pad`.

Syntax

    function COMPARE (r1 IN RAW, r2 IN RAW,
     pad RAW DEFAULT NULL) RETURN NUMBER;

Where Table C-4 describes the parameters in this function:

Table C-4 COMPARE Function Parameters

Parameter | Description
--- | ---
`r1` | is the first RAW value to be compared. This may be null and/or have a length of 0.
`r2` | is the second RAW value to be compared. This might be null and/or have a length of 0.
`pad` | is a 1 byte value used to pad the shorter RAW value.

Defaults

where "`pad`" is optional and defaults to x'00'.

Return Value

A value of 0 if the strings are null or identical. Or the position, numbered from 1, of the first mismatched byte.

Error and Warning Messages

If you receive an ORA-xxxx error or warning message, refer to the Oracle Database Error Messages guide for an explanation and information about how to handle it.

### C.1.8 CONCAT

CONCAT concatenates a set of up to 12 RAW values (`r1 - r12`) into a single RAW and returns it.

Input RAW values are appended together in the resulting RAW, left to right, in the order they appear in the parameter list. Input values need not be contiguous. Null input RAW values are skipped and the concatenation continues with the next non-null input RAW value. If the sum of the lengths of the input RAWs exceeds the maximum allowable length for a RAW (32767), an error is returned.

Syntax

    function CONCAT (r1 IN RAW DEFAULT NULL,
     r2 RAW DEFAULT NULL,
     r3 RAW DEFAULT NULL,
     r4 RAW DEFAULT NULL,
     r5 RAW DEFAULT NULL,
     r6 RAW DEFAULT NULL,
     r7 RAW DEFAULT NULL,
     r8 RAW DEFAULT NULL,
     r9 RAW DEFAULT NULL,
     r10 RAW DEFAULT NULL,
     r11 RAW DEFAULT NULL,
     r12 RAW DEFAULT NULL) RETURN RAW;

where:

"`r1 - r12`" are the RAW items to be concatenated.

Defaults

None

Return Value

A RAW value with the concatenated items.

Error and Warning Messages

If you receive an ORA-xxxx error or warning message, refer to the Oracle Database Error Messages guide for an explanation and information about how to handle it.

### C.1.9 CONVERT

CONVERT converts RAW `r` from character set `from_charset` to character set `to_charset` and returns the resulting RAW value.

Both `from_charset` and `to_charset` must specify supported character sets defined to the Oracle server.

Syntax

    function CONVERT (r IN RAW,
     to_charset IN VARCHAR2,
     from_charset IN VARCHAR2) RETURN RAW;

Where Table C-5 describes the parameters in this function:

Table C-5 CONVERT Function Parameters

Parameter | Description
--- | ---
`r` | is the RAW byte-string to be converted.
`to_charset` | is the NLS character set to convert `r` to.
`from_charset` | is the NLS character set that `r` is currently using.

Defaults

None

Return Value

A RAW string of bytes converted according to the specified character set.

Error and Warning Messages

If you receive an ORA-xxxx error or warning message, refer to the Oracle Database Error Messages guide for an explanation and information about how to handle it.

### C.1.10 COPIES

COPIES returns `n` copies of RAW `r` concatenated together.

Syntax

    function COPIES (r IN RAW,
     n IN NUMBER) RETURN RAW;

Where Table C-6 describes the parameters in this function:

Table C-6 COPIES Function Parameters

Parameter | Description
--- | ---
`r` | is the RAW value to be copied.
`n` | is the number of times to copy the RAW value. This must be a positive value.

Defaults

None

Return Value

The RAW value copied `n` times.

Error and Warning Messages

If you receive an ORA-xxxx error or warning message, refer to the Oracle Database Error Messages guide for an explanation and information about how to handle it.

### C.1.11 LENGTH

LENGTH returns the length in bytes of RAW `r`.

Syntax

    function LENGTH (r IN RAW) RETURN NUMBER;

where:

"`r`" is the byte stream to be measured.

Defaults

None

Return Value

The current length of the RAW input value.

Error and Warning Messages

If you receive an ORA-xxxx error or warning message, refer to the Oracle Database Error Messages guide for an explanation and information about how to handle it.

### C.1.12 OVERLAY

OVERLAY replaces the specified portion of RAW `target` with RAW `overlay`, beginning at byte position `pos` of `target`, and proceeding for `len` bytes.

If `overlay` has fewer than `len` bytes, then `overlay` is padded to `len` bytes using the byte specified by `pad`. If `overlay` has more than `len` bytes, then the extra bytes in `overlay` are ignored. If `len` bytes beginning at position `pos` of `target` exceeds the length of `target,` `target` is extended to contain the entire length of `overlay`. If `pos` exceeds the length of `target,` `target` is padded with `pad` bytes to position `pos` and then `target` is further extended with `overlay` bytes.

Syntax

    function OVERLAY (overlay IN RAW,
     target IN RAW,
     pos IN BINARY_INTEGER DEFAULT 1,
     len IN BINARY_INTEGER DEFAULT NULL,
     pad IN RAW DEFAULT NULL) RETURN RAW;

Where Table C-7 describes the parameters in this function:

Table C-7 OVERLAY Function Parameters

Parameter | Description
--- | ---
`overlay` | is a byte-string used to overlay the target. Bytes are always selected from the overlay RAW beginning with the leftmost byte.
`target` | is the byte-string to be overlayed.
`pos` | is the position within the target RAW, numbered from 1, at which to begin overlaying. This value must be greater than zero. This parameter is optional.
`len` | is the number of bytes to overlay. This must be greater than or equal to zero. This parameter is optional.
`pad` | is a single byte value used to pad when `len` exceeds overlay length or `pos` exceeds target length. This parameter is optional.

Defaults

Table C-8 describes the OVERLAY function defaults:

Table C-8 OVERLAY Function Defaults

Parameters | Description
--- | ---
`pos` | defaults to 1.
`len` | defaults to length of overlay.
`pad` | defaults to x'00'.

Return Value

The target byte-string overlayed as specified.

Error and Warning Messages

If you receive an ORA-xxxx error or warning message, refer to the Oracle Database Error Messages guide for an explanation and information about how to handle it.

### C.1.13 REVERSE

Reverse the byte sequence in RAW `r` from end-to-end. For example, x'0102F3' would be reversed into x'F30201' and 'xyz' would be reversed to 'zyx'. The result length is the same as the input RAW length.

Syntax

    function REVERSE (r IN RAW) RETURN RAW;

where "`r`" is the RAW value to reverse.

Defaults

None

Return Value

A RAW value containing the reverse of the input RAW value.

Error and Warning Messages

If you receive an ORA-xxxx error or warning message, refer to the Oracle Database Error Messages guide for an explanation and information about how to handle it.

### C.1.14 SUBSTR

SUBSTR extracts a portion of RAW `r`, starting at byte position `pos` and including `len` bytes.

If `pos` is positive, SUBSTR counts from the beginning of `r` to find the first byte. If `pos` is negative, SUBSTR counts backwards from the end of `r`. If `len` is not specified, SUBSTR returns all bytes to the end of `r`.

Syntax

    function SUBSTR (r IN RAW,
                         pos IN BINARY_INTEGER,
                         len BINARY_INTEGER DEFAULT NULL) RETURN RAW;

Where Table C-9 describes the parameters in this function:

Table C-9 SUBSTR Function Parameters

Parameters | Description
--- | ---
`r` | is the RAW byte-string from which a portion is to be extracted.
`pos` | is the byte position from which to start extraction. This value cannot be zero. If this value is negative, SUBSTR counts backwards from the end of `r`.
`len` | is the number of bytes from `pos` to extract from `r`. This value must be greater than zero. This parameter is optional.

Defaults

Defaults to the length of position `pos` to the end of `r`.

Return Value

The portion of `r` beginning at `pos` for `len` bytes. Or a null value if `r` is null.

Error and Warning Messages

If you receive an ORA-xxxx error or warning message, refer to the Oracle Database Error Messages guide for an explanation and information about how to handle it.

### C.1.15 TRANSLATE

TRANSLATE returns the RAW `r` after changing the bytes in `from_set` according to bytes in `to_set`.

Successive bytes in `r` are looked up in `from_set` and if found, the byte at the same offset in `to_set` is copied to the result or omitted from the result if the offset exceeds the length of `to_set`. Bytes that appear in `r` but not in `from_set` are copied to the result. Only the first (leftmost) occurrence of a byte in `from_set` is used and subsequent duplicate occurrences are ignored.

If `from_set` contains more bytes than `to_set`, the extra bytes at the end of `from_set` have no corresponding bytes in `to_set`. Any bytes in `r` matching such uncorresponded `from_set` bytes are omitted from the resulting RAW value.

TRANSLATE differs from TRANSLITERATE in the following ways:

- translation RAWs have no defaults

- `r` bytes undefined in the `to_set` translation RAW are omitted

- resulting RAW value can be shorter than the input RAW value

Syntax

    function TRANSLATE (r IN RAW,
     from_set IN RAW,
     to_set IN RAW) RETURN RAW;

Table C-10 describes the parameters in this function:

Table C-10 TRANSLATE Function Parameters

Parameter | Description
--- | ---
`r` | is the RAW source byte-string to be changed.
`from_set` | is the RAW byte-codes to be matched, if present in `r`.
`to_set` | is the RAW byte-codes to which corresponding `from_set` bytes are changed.

Defaults

None

Return Value

A RAW translated byte-string.

Error and Warning Messages

If you receive an ORA-xxxx error or warning message, refer to the Oracle Database Error Messages guide for an explanation and information about how to handle it.

### C.1.16 TRANSLITERATE

TRANSLITERATE returns the RAW `r` after replacing all occurrences of any bytes in `from_set` with the corresponding bytes in `to_set`.

Successive bytes in `r` are looked up in `from_set` and, if not found, are copied unaltered to the resulting RAW value. If found, they are replaced in the resulting RAW value by either the byte at the same offset in `to_set`, or the `pad` byte when the offset exceeds the `to_set` length. Bytes found in `r` but not found in `from_set` are copied to the result. Only the first (leftmost) occurrence of a byte in`from_set` is used; subsequent duplicate occurrences are ignored. The result of TRANSLITERATE is always the same length as RAW `r`.

If `to_set` is shorter than `from_set`, then the `pad` byte is placed in the resulting RAW value when a selected `from_set` byte has no corresponding byte in `to_set`.

TRANSLITERATE differs from TRANSLATE in the following ways:

- `r` bytes undefined in `to_set` are padded

- the resulting RAW value is always the same length as the input RAW value

Syntax

    function TRANSLITERATE (r IN RAW,
     to_set IN RAW DEFAULT NULL,
     from_set IN RAW DEFAULT NULL,
     pad IN RAW DEFAULT NULL) RETURN RAW;

Where Table C-11 describes the parameters in this function:

Table C-11 TRANSLITERATE Syntax

Item | Description
--- | ---
`r` | is the RAW source byte-string to be changed.
`to_set` | is the RAW byte-codes to which corresponding `from_set` bytes are changed This value can be of any valid RAW length.
`from_se`t | is the RAW byte-codes to be matched, if present in `r`. This value can be of any valid RAW length.
`pad` | is a 1 byte value used when `to_set` is shorter than `from_set`.

Defaults

Table C-12 describes the TRANSLITERATE function defaults:

Table C-12 Transliterate Function Defaults

Parameter | Description
--- | ---
`to_set` | defaults to a null value, and effectively extended with `pad` to the length of `from_set` as necessary.
`from_set` | defaults to x'00 through x'ff'.
`pad` | defaults to x'00'.

Return Value

A RAW transliterated byte-string.

Error and Warning Messages

If you receive an ORA-xxxx error or warning message, refer to the Oracle Database Error Messages guide for an explanation and information about how to handle it.

### C.1.17 XRANGE

XRANGE returns a RAW containing all valid 1-byte encodings in succession beginning with the value `start_byte` and ending with the value `end_byte`.

If `start_byte` is greater than `end_byte`, the succession of result bytes begin with `start_byte`, wrap from x'ff' to x'00', and end at `end_byte`.

If specified, `start_byte` and `end_byte` must be `single-byte` RAW values.

Syntax

    function XRANGE (start_byte IN RAW DEFAULT NULL,
     end_byte IN RAW DEFAULT NULL) RETURN RAW;

Where Table C-13 describes the parameters in this function:

Table C-13 XRANGE Function Parameters

Parameter | Description
--- | ---
`start_byte` | is the 1-byte beginning byte-code value of the resulting sequence.
`end_byte` | is the 1-byte ending byte-code value of the resulting sequence.

Defaults

Where Table C-14 describes the XRANGE function defaults:

Table C-14 XRANGE Function Defaults

Parameters | Description
--- | ---
`start_byte` | defaults to x'00'.
`end_byte` | defaults to x'ff'.

Return Value

A RAW value containing a succession of 1-byte hexadecimal encodings.

Error and Warning Messages

If you receive an ORA-xxxx error or warning message, refer to the Oracle Database Error Messages guide for an explanation and information about how to handle it.

## C.2 UTL_PG Functions

The UTL_PG package is an extension to PL/SQL that provides a full set of functions for converting COBOL number formats into Oracle numbers and Oracle numbers into COBOL number formats.

UTL_PG conversion format RAWs are not portable in this release. Additionally, generation of conversion format RAWs on one system and transfer to another system is not supported.

The functions listed in this section are called in the standard PL/SQL manner:

    package_name.function_name(arguments)

Specifically for UTL_PG routines, this is:

    UTL_PG.function_name(arguments)

For each function listed below, the function name, arguments and their datatypes, and the return value datatype are provided. Unless otherwise specified, the parameters are IN, not OUT, parameters.

### C.2.1 Common Parameters

The following UTL_PG functions share several similar parameters among themselves:

- RAW_TO_NUMBER

- MAKE_NUMBER_TO_RAW_FORMAT

- MAKE_RAW_TO_NUMBER_FORMAT

- NUMBER_TO_RAW

These similar parameters are described in detail in Table C-15 and then referenced only by name in subsequent tables listing the parameters for each UTL_PG function in this Appendix.

#### C.2.1.1 Common Input Parameters

Table C-15 describes the input parameters that are common to all of the UTL_PG functions:

Table C-15 Input Parameters Common to UTL_PG Function

Parameter | Description
--- | ---
`mask` | is the compiler datatype mask. This is the datatype to be converted, specified in the source language of the named compiler (`compname`). This implies the internal format of the data as encoded according to the compiler and host platform.
`maskopts` | is the compiler datatype mask options or NULL. These are additional options associated with the mask, as allowed or required, and are specified in the source language of `compname`. These can further qualify the type of conversion as necessary.
`envrnmnt` | is the compiler environment clause or NULL. These are additional options associated with the environment in which the remote data resides, as allowed or required, and is specified in the source language of compname. This parameter typically supplies aspects of data conversion dictated by customer standards, such as decimal point or currency symbols if applicable.
`compname` | is the compiler name. The only supported value is IBMVSCOBOLII.
`compopts` | is the compiler options or NULL.
`nlslang` | is the zoned decimal code page specified in Oracle NLS format, `language_territory.charset`. This defaults to AMERICAN_AMERICA.WE8EBCDIC37C.
`wind` | is the warning indicator. A Boolean indicator which controls whether conversion warning messages are to be returned in the wmsgblk OUT parameter.
`wmsgbsiz` | is the warning message block declared size in bytes. It is a BINARY_INTEGER set to the byte length of `wmsgblk`. The warning message block must be at least 512 and not more than 8192 bytes in length. When declaring `wmsgblk`, plan on approximately 512 bytes for each warning returned, depending on the nature of the requested conversion.

#### C.2.1.2 Common Output Parameter

Table C-16 describes the output parameter that is common to the UTL_PG functions:

Table C-16 Output Parameters Common to UTL_PG Functions

Parameter | Description
--- | ---
`wmsgblk` | is the warning message block. It is a RAW value which can contain multiple warnings in both full message and substituted parameter formats, if `wind` is TRUE. This parameter should be passed to the WMSGCNT function to test if warnings were issued and to WMSG to extract any warning that are present. If `wind` is TRUE and no warnings are issued or if `wind` is FALSE, the length of `wmsgblk` is 0. This parameter does not need to be reset before each use. The warning message is documented in the Oracle Database 10g Error Messages manual. This parameter must be allocated and passed as a parameter in all cases, regardless of how `wind` is specified.

### C.2.2 RAW_TO_NUMBER

RAW_TO_NUMBER converts a RAW byte-string `r` from the remote host internal format specified by `mask,` `maskopts,` `envrnmnt,` `compname,` `compopts,` and `nlslang` into an Oracle number.

Warnings are issued, if enabled, when the conversion specified conflicts with the conversion implied by the data or when conflicting format specifications are supplied.

For detailed information about the `mask,` `maskopts,` `envrnmnt,` `compname`, and `compopts` arguments, refer to "NUMBER_TO_RAW and RAW_TO_NUMBER Argument Values".

Syntax

    function RAW_TO_NUMBER (r IN RAW,
     mask IN VARCHAR2,
     maskopts IN VARCHAR2,
     envrnmnt IN VARCHAR2,
     compname IN VARCHAR2,
     compopts IN VARCHAR2,
     nlslang IN VARCHAR2,
     wind IN BOOLEAN,
     wmsgbsiz IN BINARY_INTEGER,
     wmsgblk OUT RAW) RETURN NUMBER;

Where Table C-17 describes the parameters in this function:

Table C-17 RAW_TO_NUMBER Function Parameters

Parameter | Description
--- | ---
`r` | is the remote host data to be converted.
`mask` | is the compiler datatype mask.
`maskopts` | are the compiler datatype mask options or NULL.
`envrnmnt` | is the compiler environment clause or NULL.
`compname` | is the compiler name.
`compopts` | are the compiler options or NULL.
`nlslang` | is the zoned decimal code page in Oracle NLS format.
`wind` | is a warning indicator.
`wmsgbsiz` | is the warning message block size in bytes.
`wmsgblk` | is the warning message block. This is an OUT parameter.

Defaults and Optional Parameters

Table C-18 describes the default and optional parameters of the RAW_TO_NUMBER function:

Table C-18 Optional and Default Parameters of the RAW_TO_NUMBER Function

Parameters | Description
--- | ---
`maskopts` | null allowed, no default value
`envrnmnt` | null allowed, no default value
`compopts` | null allowed, no default value

Return Value

An Oracle number corresponding in value to `r`.

Error and Warning Messages

If you receive an ORA-xxxx error or warning message, refer to the Oracle Database Error Messages guide for an explanation and information about how to handle it.

### C.2.3 NUMBER_TO_RAW

NUMBER_TO_RAW converts an Oracle number `n` of declared precision and scale into a RAW byte-string in the remote host internal format specified by `mask`, `maskopts,` `envrnmnt,` `compname,` `compopts`, and `nlslang`.

Warnings are issued, if enabled, when the conversion specified conflicts with the conversion implied by the data or when conflicting format specifications are supplied.

For detailed information about the `mask,` `maskopts,` `envrnmnt,` `compname,` and `compopts` arguments, refer to"NUMBER_TO_RAW and RAW_TO_NUMBER Argument Values".

Syntax

    function NUMBER_TO_RAW (n IN NUMBER,
     mask IN VARCHAR2,
     maskopts IN VARCHAR2,
     envrnmnt IN VARCHAR2,
     compname IN VARCHAR2,
     compopts IN VARCHAR2,
     nlslang IN VARCHAR2,
     wind IN BOOLEAN,
     wmsgbsiz IN BINARY_INTEGER,
     wmsgblk OUT RAW) RETURN RAW;

Where Table C-19 describes the parameters in this function:

Table C-19 NUMBER_TO_RAW Function Parameters

Parameter | Description
--- | ---
`n` | is the Oracle number to be converted.
`mask` | is the compiler datatype mask.
`maskopts` | are the compiler datatype mask options or NULL.
`envrnmnt` | is the compiler environment clause or NULL.
`compname` | is the compiler name.
`compopts` | are the compiler options or NULL.
`nlslang` | is the zoned decimal code page in Oracle NLS format.
`wind` | is a warning indicator`.`
`wmsgbsiz` | is the warning message block size in bytes.
`wmsgblk` | is the warning message block. This is an OUT parameter.

Defaults and Optional Parameters

Table C-20 describes the defaults and optional parameters for the NUMBER_TO_RAW function:

Table C-20 Defaults and Optional Parameters for NUMBER_TO_RAW Function

Parameter | Description
--- | ---
`maskopts` | null allowed, no default value
`envrnmnt` | null allowed, no default value
`compopts` | null allowed, no default value

Return Value

A RAW value corresponding in value to `n`.

Error and Warning Messages

If you receive an ORA-xxxx error or warning message, refer to the Oracle Database Error Messages guide for an explanation and information about how to handle it.

### C.2.4 MAKE_RAW_TO_NUMBER_FORMAT

MAKE_RAW_TO_NUMBER_FORMAT makes a RAW_TO_NUMBER format conversion specification used to convert a RAW byte-string from the remote host internal format specified by `mask,` `maskopts,` `envrnmnt,` `compname,` `compopts,` and `nlslang` into an Oracle number of comparable precision and scale.

Warnings are issued, if enabled, when the conversion specified conflicts with the conversion implied by the data or when conflicting format specifications are supplied.

This function returns a RAW value containing the conversion format which can be passed to UTL_PG.RAW_TO_NUMBER_FORMAT.

For detailed information about the `mask,` `maskopts`, `envrnmnt`, `compname`, and `compopts` arguments, refer to "NUMBER_TO_RAW and RAW_TO_NUMBER Argument Values".

Syntax

    function MAKE_RAW_TO_NUMBER_FORMAT (mask IN VARCHAR2,
     maskopts IN VARCHAR2,
     envrnmnt IN VARCHAR2,
     compname IN VARCHAR2,
     compopts IN VARCHAR2,
     nlslang IN VARCHAR2,
     wind IN BOOLEAN,
     wmsgbsiz IN BINARY_INTEGER,
     wmsgblk OUT RAW) RETURN RAW;

Where Table C-21 describes the parameters in this function:

Table C-21 MAKE_RAW_TO_NUMBER_FORMAT Function Parameters

Parameter | Description
--- | ---
`mask` | is the compiler datatype mask.
`maskopts` | are the compiler datatype mask options or NULL.
`envrnmnt` | is the compiler environment clause or NULL.
`compname` | is the compiler name.
`compopts` | are the compiler options or NULL.
`nlslang` | is the zoned decimal code page in Oracle NLS format.
`wind` | is a warning indicator.
`wmsgbsiz` | is the warning message block size in bytes.
`wmsgblk` | is the warning message block. This is an OUT parameter.

Defaults and Optional Parameters

Table C-22 describes the defaults and optional parameters of the MAKE_RAW_TO_NUMBER_FORMAT function:

Table C-22 Default and Optional MAKE_RAW_TO_NUMBER_FORMAT Parameters

Parameter | Description
--- | ---
`maskopts` | null allowed, no default value
`envrnmnt` | null allowed, no default value
`compopts` | null allowed, no default value

Return Value

A RAW(2048) format conversion specification for RAW_TO_NUMBER.

Error and Warning Messages

If you receive an ORA-xxxx error or warning message, refer to the Oracle Database Error Messages guide for an explanation and information about how to handle it.

### C.2.5 MAKE_NUMBER_TO_RAW_FORMAT

MAKE_NUMBER_TO_RAW_FORMAT makes a NUMBER_TO_RAW format conversion specification used to convert an Oracle number of declared precision and scale to a RAW byte-string in the remote host internal format specified by `mask,` `maskopts,` `envrnmnt`, `compname`, `compopts`, and `nlslang.`

Warnings are issued, if enabled, when the conversion specified conflicts with the conversion implied by the data or when conflicting format specifications are supplied.

This function returns a RAW value containing the conversion format which can be passed to UTL_PG.NUMBER_TO_RAW_FORMAT. The implementation length of the result format RAW is 2048 bytes.

For detailed information about the `mask,` `maskopts,` `envrnmnt,` `compname`, and `compopts` arguments, refer to "NUMBER_TO_RAW and RAW_TO_NUMBER Argument Values".

Syntax

    function MAKE_NUMBER_TO_RAW_FORMAT (mask IN VARCHAR2,
     maskopts IN VARCHAR2,
     envrnmnt IN VARCHAR2,
     compname IN VARCHAR2,
     compopts IN VARCHAR2,
     nlslang IN VARCHAR2,
     wind IN BOOLEAN,
     wmsgbsiz IN BINARY_INTEGER,
     wmsgblk OUT RAW) RETURN RAW;

Where Table C-23 describes the parameters in this function:

Table C-23 MAKE_NUMBER_TO_RAW_FORMAT Function Parameters

Parameter | Description
--- | ---
`mask` | is the compiler datatype mask.
`maskopts` | are the compiler datatype mask options or NULL.
`envrnmnt` | is the compiler environment clause or NULL.
`compname` | is the compiler name.
`compopts` | are the compiler options or NULL.
`nlslang` | is the zoned decimal code page in Oracle NLS format.
`wind` | is a warning indicator`.`
`wmsgbsiz` | is the warning message block size in bytes.
`wmsgblk` | is the warning message block. This is an OUT parameter.

Defaults and Optional Parameters

Table C-24 describes the defaults and optional parameters for the MAKE_NUMBER_TO_RAW_FORMAT function:

Table C-24 Optional, Default Parameters: MAKE_NUMBER_TO_RAW_FORMAT

Parameter | Description
--- | ---
`maskopts` | null allowed, no default value
`envrnmnt` | null allowed, no default value
`compopts` | null allowed, no default value

Return Value

A RAW(2048) format conversion specification for NUMBER_TO_RAW.

Error and Warning Messages

If you receive an ORA-xxxx error or warning message, refer to the Oracle Database Error Messages guide for an explanation and information about how to handle it.

### C.2.6 RAW_TO_NUMBER_FORMAT

RAW_TO_NUMBER_FORMAT converts, according to the RAW_TO_NUMBER conversion format `r2nfmt`, a RAW byte-string `rawval` in the remote host internal format into an Oracle number.

Syntax

    function RAW_TO_NUMBER_FORMAT (rawval IN RAW,
     r2nfmt IN RAW) RETURN NUMBER;

where Table C-25 describes the parameters in this function:

Table C-25 RAW_TO_NUMBER_FORMAT Function Parameters

Parameter | Description
--- | ---
`rawval` | is the remote host data to be converted.
`r2nfmt` | is a RAW(2048) format specification returned from MAKE_RAW_TO_NUMBER_FORMAT.

Defaults

None

Return Value

An Oracle number corresponding in value to `r`.

Error and Warning Messages

If you receive an ORA-xxxx error or warning message, refer to the Oracle Database Error Messages guide for an explanation and information about how to handle it.

### C.2.7 NUMBER_TO_RAW_FORMAT

NUMBER_TO_RAW_FORMAT converts, according to the NUMBER_TO_RAW conversion format `n2rfmt`, an Oracle number `numval` of declared precision and scale into a RAW byte-string in the remote host internal format.

Syntax

    function NUMBER_TO_RAW_FORMAT (numval IN NUMBER,
     n2rfmt IN RAW) RETURN RAW;

Where Table C-26 describes the parameters in this function:

Table C-26 NUMBER_TO_RAW_FORMAT Function Parameters

Parameters | Description
--- | ---
`numval` | is the Oracle number to be converted.
`n2rfmt` | is a RAW(2048) format specification returned from MAKE_NUMBER_TO_RAW_FORMAT.

Defaults

None

Return Value

A RAW value corresponding in value to `n`.

Error and Warning Messages

If you receive an ORA-xxxx error or warning message, refer to the Oracle Database Error Messages guide for an explanation and information about how to handle it.

### C.2.8 WMSGCNT

WMSGCNT tests a `wmsgblk` to determine how many warnings, if any, are present.

Syntax

    function WMSGCNT (wmsgblk IN RAW) RETURN BINARY_INTEGER;

Where Table C-27 describes the parameter in this function.

Table C-27 WMSGCNT Function Parameter

Parameter | Description
--- | ---
`wmsgblk` | is the warning message block returned from one of the following functions: MAKE_NUMBER_TO_RAW_FORMAT MAKE_RAW_TO_NUMBER_FORMAT NUMBER_TO_RAW RAW_TO_NUMBER

Defaults

None

Return Value

A BINARY_INTEGER value equal to the count of warnings present in the RAW `wmsgblk`.

Table C-28 lists possible returned values:

Table C-28 WMSGCNT Return Values

| Description
--- | ---
`>0` | indicates a count of warnings present in `wmsgblk`.
`0` | indicates that no warnings are present in `wmsgblk`.

Error and Warning Messages

If you receive an ORA-xxxx error or warning message, refer to the Oracle Database Error Messages guide for an explanation and information about how to handle it.

### C.2.9 WMSG

WMSG extracts a warning message specified by `wmsgitem` from `wmsgblk`.

Syntax

    function WMSG (wmsgblk IN RAW,
     wmsgitem IN BINARY_INTEGER,
     wmsgno OUT BINARY_INTEGER,
     wmsgtext OUT VARCHAR2,
     wmsgfill OUT VARCHAR2) RETURN BINARY_INTEGER;

Where Table C-29 describes the parameters in this function:

Table C-29 WMSG Function Parameters

Parameter | Description
--- | ---
`wmsgblk` | is a RAW warning message block returned from one of the following functions: MAKE_NUMBER_TO_RAW_FORMAT MAKE_RAW_TO_NUMBER_FORMAT NUMBER_TO_RAW RAW_TO_NUMBER
`wmsgitem` | is a BINARY_INTEGER value specifying which warning message to extract, numbered from 0 for the first warning through `n` minus 1 for the `n`th warning.
`wmsgno` | is an OUT parameter containing the BINARY_INTEGER (hexadecimal) value of the warning number. This value, after conversion to decimal, is documented in the Oracle Database 10g Error Messages manual.
`wmsgtext` | is a VARCHAR2 OUT parameter value containing the fully-formatted warning message in ORA-xxxxx format, where xxxxx is the decimal warning number documented in the Oracle Database 10g Error Messages manual.
`wmsgfill` | is a VARCHAR2 OUT parameter value containing the list of warning message parameters to be substituted into a warning message in the following format: warnparm1;;warnparm2;;...;;warnparmn where each warning parameter is delimited by a double semicolon.

Defaults

None

Return Value

A BINARY_INTEGER value containing a status return code.

A return code of "0" indicates that `wmsgno`, `wmsgtext`, and `wmsgfill` are assigned and valid.

Error and Warning Messages

If you receive an ORA-xxxx error or warning message, refer to the Oracle Database Error Messages guide for an explanation and information about how to handle it.

Table C-30 describes the error messages you could receive:

Table C-30 WMSG Function Errors

Error | Description
--- | ---
`-1` | indicating the warning specified by `wmsgitem` was not found in `wmsgblk`.
`-2` | indicating an invalid message block.
`-3` | indicating `wmsgblk` is too small to contain the warning associated with `wmsgitem`. A partial or no warning message might be present for this particular `wmsgitem`.
`-4` | indicating there are too many substituted warning parameters.

## C.3 NUMBER_TO_RAW and RAW_TO_NUMBER Argument Values

This table lists the valid values for the format arguments for NUMBER_TO_RAW and RAW_TO_NUMBER and related functions. Following are examples of some valid COBOL picture masks. Any valid COBOL picture mask may be used. Refer to the appropriate IBM COBOL programming guides for an explanation of COBOL picture masks.

    mask: COBOL picture mask

      PIC  9(n)         where 1 <= n   <= 18
      PIC S9(n)         where 1 <= n   <= 18
      PIC  9(n)V9(s)    where 1 <= n+s <= 18
      PIC S9(n)V9(s)    where 1 <= n+s <= 18
      PIC S9999999V99
      PIC V99999
      PIC SV9(5)
      PIC  999.00
      PIC  99/99/99
      PIC  ZZZ.99
      PIC  PPP99
      PIC +999.99
      PIC  999.99+
      PIC -999.99
      PIC  999.99-
      PIC $$$$$,$$$.99
      PIC $9999.99DB
      PIC $9999.99CR

    maskopts: COBOL picture mask options

      COMP
      USAGE IS COMP
      USAGE IS COMPUTATIONAL
      COMP-3
      USAGE IS COMP-3
      USAGE IS COMPUTATIONAL-3
      COMP-4
      USAGE IS COMP-4
      USAGE IS COMPUTATIONAL-4
      DISPLAY
      USAGE IS DISPLAY
      SIGN IS LEADING
      SIGN IS LEADING SEPARATE
      SIGN IS LEADING SEPARATE CHARACTER
      SIGN IS TRAILING
      SIGN IS TRAILING SEPARATE
      SIGN IS TRAILING SEPARATE CHARACTER

    envrnmnt: COBOL environment clause

      CURRENCY SIGN IS x where x is a valid currency sign character
      DECIMAL-POINT IS COMMA

    compname: COBOL compiler name

      IBMVSCOBOLII

    compopts: COBOL compiler options

      (no values are supported at this time)